---
id: namespaces
title: What is a Temporal Namespace?
sidebar_label: Namespaces
description: This guide covers everything about Namespaces within the Temporal Platform, highlighting their role in Workflow isolation, setting up, registering, and managing Namespaces, and the concept and benefits of Global Namespaces.
slug: /namespaces
toc_max_heading_level: 4
keywords:
  - namespaces
tags:
  - Concepts
  - Namespaces
---

This guide provides a comprehensive overview of Namespaces.

A Namespace is a unit of isolation within the Temporal Platform.

A single Namespace is still multi-tenant.

### Usage

Namespaces are created on the Temporal Service, and provide a range of controls to achieve isolation on Workflow Executions.

- Namespaces are a mechanism for resource isolation. Heavy traffic from one Namespace will not impact other Namespaces running on the same Temporal Service.
  For example, you can use Namespaces to match the development lifecycle by having separate `dev` and `prod` Namespaces.
- If no other Namespace is specified, the Temporal Service uses the Namespace "default" for all Temporal SDKs and the Temporal CLI.
  See the [Registration](#registration) section for details.
- Namespaces created on self-hosted Temporal Service are case-sensitive. For example, `foo` and `Foo` are two different Namespaces.
  On Temporal Cloud, Namespaces are case-insensitive, and we recommend using lowercase for Namespace names to avoid potential issues.
- **Membership:** [Task Queue](/workers#task-queue) names and [Workflow Ids](/workflows#workflow-id) must all correspond to a specific Namespace.
  For example, when a Workflow Execution is spawned, it does so within a specific Namespace.
- **Uniqueness:** Temporal guarantees a unique Workflow Id within a Namespace.
  Workflow Executions may have the same Workflow Id if they are in different Namespaces.
- **Namespace Configuration:** Various configuration options like the [Retention Period](/clusters#retention-period) and the [Archival](/clusters#archival) destination are configured per Namespace through a special CRUD API or through the [Temporal CLI](/cli/cmd-options#namespace).

### Registration

Registering a Namespace creates the Namespace on the Temporal Service.
When you register your Namespace, you must also set the [Retention Period](/clusters#retention-period) for the Namespace.

On Temporal Cloud, use the [Temporal Cloud UI](/cloud/namespaces#create-a-namespace) or [tcld commands](https://docs.temporal.io/cloud/tcld/namespace/) to create and manage Namespaces.

On self-hosted Temporal Service, you can register your Namespaces using the Temporal CLI (recommended) or programmatically using APIs. Note that these APIs and Temporal CLI commands will not work with Temporal Cloud.

All SDKs require a Namespace on the Temporal Service (or Temporal Cloud) for their Client calls. If not set using Client options, the Workflow Client API looks for the `default` Namespace. If there is no default Namespace registered with your Temporal Service (or Temporal Cloud), all calls will throw errors.
You must register your Namespace with the Temporal Service (or Temporal Cloud) before setting it in your Client.

On self-hosted Temporal Service, you can register your Namespaces in the following ways:

- In your Temporal Service setup, create your Namespaces, including the default, in your setup script.
  For example:

  - If deploying through Docker Compose or using the [auto-setup image](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) in a custom Docker Compose application, the Namespace "default" is created, through the auto-setup script.
  - If deploying through the [Temporal Helm charts](https://github.com/temporalio/helm-charts), you can create the "default" Namespace by using the Temporal CLI; for example, `temporal operator namespace create --namespace default`

- Use the `temporal operator namespace create` or `temporal operator namespace update` command with the `--retention` modfiier to register your Namespaces, one at a time, and set the Retention Period on each.

  - [How to create a new Namespace using the Temporal CLI](/cli/operator#create)
  - [How to create a new Namespace using the Go SDK](/develop/go/namespaces#register-namespace)
  - [How to create a new Namespace using the Java SDK](/develop/java/namespaces#register-namespace)

- In your Client program, register your Namespace using `RegisterNamespaceRequest` API available in all the SDKs.

Note that registering a Namespace takes up to 15 seconds to complete. Ensure that you are waiting for this process to complete before making calls to the Namespace.

### Manage Namespaces

Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.

On Temporal Cloud, use the [Temporal Cloud UI](/cloud/namespaces) or [tcld commands](/cloud/tcld/namespace/) to manage Namespaces.

On self-hosted Temporal Service, you can manage your registered Namespaces using the Temporal CLI (recommended) or programmatically using APIs.

{/* Technically correct but is this confusing for people since you can do this for non-self-hosted: _/}
{/_ Note that these APIs and temporal CLI commands will not work with Temporal Cloud. */}

- [How to manage Namespaces using the Go SDK](/develop/go/namespaces#manage-namespaces)
- [How to manage Namespaces using the Java SDK](/develop/java/namespaces#manage-namespaces)

- Update information and configuration for a registered Namespace on your Temporal Service:

  - With the Temporal CLI: [`temporal operator namespace update`](/cli/operator#update)
  - Use the Update Namespace API to update configuration on a Namespace.

- Get details for a registered Namespace on your Temporal Service:

  - With the Temporal CLI: [`temporal operator namespace describe`](/cli/operator#describe)
  - Use the Describe Namespace to return information and configuration details for a registered Namespace.

- Get details for all registered Namespaces on your Temporal Service:

  - With the Temporal CLI: [`temporal operator namespace list`](/cli/operator#list)
  - Use the List Namespace API to return information and configuration details for all registered Namespaces on your Temporal Service.

- Deprecate a Namespace: The Deprecate Namespace updates the state of a registered Namespace to "DEPRECATED". Once a Namespace is deprecated, you cannot start new Workflow Executions on it. All existing and running Workflow Executions on a deprecated Namespace will continue to run.

- Delete a Namespace: Deletes a Namespace and all Workflow Executions on the Namespace. Note that this API is supported for Temporal Server version 1.17 and later.
- With the Temporal CLI: [`temporal operator namespace delete`](/cli/operator#delete).
- Use the DeleteNamespace API to delete a registered Namespaces. All the running Workflow Executions on a deleted Namespace are also deleted.

### Setting

Set Namespaces in your SDK Client to isolate your Workflow Executions to the Namespace.
If you do not set a Namespace, all Workflow Executions started using the Client will be associated with the "default" Namespace. This means, you must have a default Namespace called "default" registered with your Temporal Service. See [Registration](#registration) for details.

{/* TODO add sample for this to link to -[How to set the Namespace for a Temporal Client](/) */}

- [How to list Namespaces in a Temporal Service using the Temporal CLI](/cli/operator#list)
- [How to view (describe) Namespace metadata and details using the Temporal CLI](/cli/operator#describe)

## What is a Global Namespace? {#global-namespace}

A Global Namespace is a [Namespace](/namespaces) that exists across Clusters when [Multi-Cluster Replication](/clusters#multi-cluster-replication) is set up.

- [How to register a Global Namespace](/cli/operator#create)
- [How to change the active Cluster for a Global Namespace](/cli/operator#update)

The Global Namespace feature enables Workflow Executions to progress through another Cluster in the event of a failover.

A Global Namespace may be replicated to any number of Clusters, but is active in only one Cluster at any given time.

For a failover to be successful, Worker Processes must be polling for Tasks for the Global Namespace on all Clusters.

A Global Namespace has a failover version.
Because a failover can be triggered from any Cluster, the failover version prevents certain conflicts from occurring if a failover is mistakenly triggered simultaneously on two Clusters.

Only the active Cluster dispatches [Tasks](/workers#task); however, certain conflicts are possible.
Unlike regular Namespaces, which provide at-most-once semantics for an Activity Execution, Global Namespaces can support only at-least-once semantics (see [Conflict resolution](/clusters#conflict-resolution)).
Worker Processes on the standby Clusters are idle until a failover occurs and their Cluster becomes active.

Temporal Application API calls made to a non-active Cluster are rejected with a **NamespaceNotActiveError** which contains the name of the current active Cluster.
It is the responsibility of the Temporal Application to call the Cluster that is currently active.
